home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume91 / devices / sanainov / part04 / driver.txt
Text File  |  1991-11-16  |  31KB  |  804 lines
  1.  
  2. SANA-II Network Device Driver Specification
  3.  
  4. November 7, 1991
  5. Draft for Final Comments and Approval
  6.  
  7.  
  8. Dale Larson, Greg Miller
  9. Amiga Networking Group, New Siberia Office
  10.  
  11.  
  12.  
  13. Introduction
  14.  
  15. The SANA-II Network Device Driver Specification is a standard for the
  16. interface to any Amiga networking hardware.  It is a specification for an
  17. Amiga software interface to the data link layer in the ISO 7-Layer Reference
  18. Model of Open Systems Interconnection.  All Amiga network hardware vendors
  19. should supply a SANA-II device driver for their hardware. All protocol writers
  20. should talk to SANA-II device drivers rather than to network hardware.  Any
  21. protocol stack should work with any SANA-II device driver.  The standard has
  22. been kept simple and straight-forward so that SANA-II device drivers should be
  23. easy to write and to use.  They should be highly efficient and have low
  24. resource usage.  Any SANA-II device driver should behave very much like any
  25. other SANA-II device driver.
  26.  
  27. Application writers must not use SANA-II Device Drivers directly.
  28. Applications must use the API provided by the network protocol software the
  29. application supports.  It is hoped that a standard network API for all Amigas
  30. will be made available by Commodore in the near future.
  31.  
  32. This version of the standard addresses issues from the original SANA-II
  33. standard which were raised in the 1991 North American and European Amiga
  34. DevCons as well as in the conversion of existing protocols to the use of the
  35. standard.  This draft reflects several rounds of comments from active
  36. implementors of SANA-II software.  Most of the changes are simplifications and
  37. should be easy to incorporate into any work in progress.  The changes should
  38. make the writing and use of SANA-II drivers much easier.  Commodore's internal
  39. versions of the A2065 and other drivers and the AS225 software package are
  40. currently compliant with this version of the SANA-II spec.
  41.  
  42. This version of the specification is very solid and will stand as final unless
  43. comments containing very compelling objections are received by December 31,
  44. 1991.  All SANA-II device drivers and software utilizing those drivers should
  45. be written to this version of the specification.
  46.  
  47. Distribution of this version of the standard is unlimited.
  48.  
  49. Comments should be emailed to dlarson@cmbvax.commodore.com or sent to Dale
  50. Larson, Software Engineer, Commodore, 1200 Wilson Drive, West Chester, PA
  51. 19380, USA.
  52.  
  53.  
  54. Changes
  55.  
  56. Most changes are explained in detail below, but for those already familiar
  57. with the 1991 DevCon draft of the SANA-II standard, here is a summary list of
  58. the important points:
  59.  
  60. - Packet type specification has been drastically simplified.  Protocols no
  61. longer specify any framing information -- packet magic is eliminated and a
  62. convention is adopted for handling the framing problem faced by ethernet
  63. drivers.
  64.  
  65. - NetBuffs are removed from the standard and replaced with a function callback.
  66.  
  67. - Station aliasing has been eliminated from the standard.
  68.  
  69. - Since the IOSana2Req structure had to be changed anyway, many names in
  70. <devices/sana2.h> have been changed to be more consistent with other system
  71. names. It is believed that global search and replace should make this a mostly
  72. trivial change and that the benefits gained from consistent naming outweigh
  73. the inconvenience to those few who have existing SANA-II code.
  74.  
  75. - Events are now defined as a bit mask rather than as scalars.
  76.  
  77.  
  78. Acknowledgements
  79.  
  80. Many people and companies have contributed to the SANA-II Network Device
  81. Driver Specification.  The original SANA-II autodocs and includes were put
  82. together by Ray Brand, Perry Kivolowitz (ASDG) and Martin Hunt.  Those
  83. original documents evolved to their current state and grew to include this
  84. document at the hands of Dale Larson and Greg Miller.  Randell Jesup has
  85. provided sage advice on several occasions and the buffer management callback
  86. mechanism was his idea.  Dale Luck (GfxBase) and Rick Spanbauer (Ameristar
  87. Technologies) have provided valuable comments throughout the process.  Nicolas
  88. Benezan (ADONIS) provided many very detailed and useful comments on weaknesses
  89. in late drafts of the specification.  Thanks to all the above and the numerous
  90. others who have contributed with their comments, questions and discussions.
  91.  
  92.  
  93. Unresolved Issues
  94.  
  95. Unfortunately, it isn't possible to completely isolate network protocols from
  96. the hardware they run on.  Hardware types and addressing both remain somewhat
  97. hardware-dependent in spite of our efforts.  See the "Packet Type" section for
  98. an explanation of how packet types are handled and why protocols cannot be
  99. isolated from them.  See the "Addressing" section for an explanation of how
  100. addressing is handled any why protocols cannot be isolated from it.
  101.  
  102. Finally, some protocol standards are simply very hardware specific.  They have
  103. particular issues which can't be dealt with from a general data link layer
  104. specification designed to isolate protocols from hardware.  For example,
  105. TCP/IP RFC 1201 cannot be implemented without a special hardware driver.  The
  106. impact of such issues should be negligible for most protocols running on most
  107. hardware, and the issues won't be made significantly more difficult to address
  108. by virtue of existence the SANA-II standard.
  109.  
  110.  
  111. Driver Form
  112.  
  113. SANA-II device drivers are Amiga Exec device drivers.  They have an extended
  114. IORequest structure and a number of extended commands for network statistics,
  115. broadcast/multicast, addressing and unexpected packets.  The Amiga ROM Kernel
  116. Reference Manual: Devices includes information on how to construct an Exec
  117. device.  We plan to release source to an example SANA-II device driver in the
  118. near future.
  119.  
  120.  
  121. Buffer Management
  122.  
  123. Most Exec device drivers read and write contiguous blocks of data and keep
  124. internal buffers.  Networking software is very good at physically fragmenting
  125. a logical block of data with headers and trailers as well as requiring
  126. dynamically tunable buffers.  To allow the efficient implementation of
  127. networking protocols therefore requires a non-contiguous physical data
  128. structure with a buffering scheme which is easily externally tunable.
  129.  
  130. The original SANA-II device driver specification therefore called for drivers
  131. to have no internal buffers and to get all buffers from protocols in the form
  132. of a data structure called a NetBuff. Hence, all protocols were required to
  133. use NetBuffs.  This was highly unsatisfactory since most protocols are
  134. implemented from an existing code base which includes its own buffer
  135. management scheme.
  136.  
  137. To solve this problem, the standard has been revised so that drivers still
  138. have no internal buffers, but now they read and write to and from an abstract
  139. data structure via calls to functions provided by the protocol.  The protocol
  140. must provide two functions -- one to copy data to the abstract data structure
  141. and one to copy data from the abstract data structure.  The protocol can
  142. therefore use it's choice of data structure for buffer management and allow
  143. this to be used by the driver in order to have very efficient memory and CPU
  144. usage overall.
  145.  
  146. The Sana2IOReq contains a pointer to data and the length of the data pointed
  147. to, but a driver is allowed to make no assumptions about how the data is
  148. stored and therefore cannot directly manipulate or examine the buffer in any
  149. manner whatsoever other than by calling the protocol-provided functions.
  150.  
  151. At OpenDevice() a protocol points ios2_BufferManagment to a list of tags which
  152. include pointers to the functions required by the driver.  The driver makes
  153. sure that all required functions are supplied and fails the open if they are
  154. not.  If the open is successful, the driver points ios2_BufferManagement to a
  155. magic cookie which it uses from then on to access these functions.  The driver
  156. could in theory choose to just copy the taglist to driver-owned memory and
  157. then to parse the list for every IORequest, but it is much more efficient for
  158. the driver to create some sort of table of functions and to point
  159. ios2_BufferManagement to that table.
  160.  
  161. The specification currently includes only two tags for the OpenDevice()
  162. ios2_BufferManagement taglist:
  163.  
  164. S2_CopyToBuff    -  This is a pointer to a function which conforms to the
  165.             CopyToBuff autodoc.
  166.  
  167. S2_CopyFromBuff  -  This is a pointer to a function which conforms to the
  168.             CopyFromBuff autodoc.
  169.  
  170.  
  171. Opening a SANA-II Device
  172.  
  173. As when opening any other Exec device, on the call to OpenDevice() a SANA-II
  174. device is passed an IORequest structure to initialize for use by the opener.
  175. This structure is copied by the opener if it desires to use multiple async
  176. requests.  The SANA-II IORequest is defined as follows:
  177.  
  178.     struct IOSana2Req
  179.     {
  180.         struct IORequest ios2_Req;
  181.         ULONG ios2_WireError;
  182.         ULONG ios2_PacketType;
  183.         UBYTE ios2_SrcAddr[SANA2_MAX_ADDR_BYTES];
  184.         UBYTE ios2_DstAddr[SANA2_MAX_ADDR_BYTES];
  185.         ULONG ios2_DataLength;
  186.         void *ios2_Data;
  187.         void *ios2_StatData;
  188.         void *ios2_BufferManagement;
  189.     };
  190.  
  191.  
  192.     ios2_Req
  193. A standard Exec device IORequest.
  194.  
  195.     WireError
  196. A more specific device code which may be set when there is an
  197. io_Error.
  198.  
  199.     PacketType
  200. The type of packet requested.
  201.  
  202.     SrcAddr
  203. The device fills in this field with the interface address of the source of the
  204. packet that satisfied a read command. The bytes used to hold the address will
  205. be left justified but the bit layout is dependent on the particular type of
  206. network.
  207.  
  208.     DstAddr
  209. This field is filled in with the interface destination address of the packet
  210. for a send command. The bytes used to hold the address will be left justified
  211. but the bit layout is dependent on the particular type of network.
  212.  
  213.     DataLength
  214. The requestor fills this field with the amount of data available in the
  215. buffer. The device fills in this field with the size of the packet data as it
  216. was sent on the wire. This does not include the header and trailer
  217. information. Depending on the network type and protocol type, the driver may
  218. have to calculate this value. This is generally used only for reads and writes
  219. (including broadcast and multicast).
  220.  
  221.     Data
  222. A pointer to some abstract data structure containing packet data.  Drivers may
  223. not directly manipulate or examine anything pointed to by Data!  This pointer
  224. is generally used only for reads and writes (including broadcast and
  225. multicast).
  226.  
  227.     StatData
  228. Pointer to a data area in memory to place a snapshot of device statistics.
  229. The data area must be long word aligned.  This pointer is only used on calls
  230. to the statistics commands.
  231.  
  232.     BufferManagement
  233. A pointer to a taglist when OpenDevice() is called.  Functions pointed to in the
  234. taglist are called by the device when processing IORequests from the opener.
  235. When returned from OpenDevice(), this field contains a pointer to driver
  236. private information used to access these functions.
  237.  
  238. The flags used with the device on OpenDevice() are (SANA2OPB_xxx):
  239.  
  240.     MINE
  241. Exclusive access to the unit requested.
  242.  
  243.     PROM
  244. Promiscuous mode requested.
  245.  
  246.  
  247. The flags used during I/O requests are (SANA2IOB_xxx):
  248.  
  249.     RAW
  250. Raw packet read/write requested.
  251.  
  252.     BCAST
  253. Broadcast packet (received).
  254.  
  255.     MCAST
  256. Multicast packet (received).
  257.  
  258.     QUICK
  259. Quick IO requested.
  260.  
  261.  
  262. Packet Type
  263.  
  264. Network frames always have a type field associated with them.  These type
  265. fields vary in length, position and meaning by frame type (frames types
  266. generally correspond one-to-one with hardware types, but see "Ethernet Packet
  267. Types" below.).  The meaning of the type numbers are always carefully defined
  268. and every type number is registered with some official body.  You must not use
  269. a type number which is not registered with the governing body for the standard
  270. hardware you are accessing.  Basically, this means that if you want to write a
  271. new protocol (rather than implementing an existing one), you've got a lot of
  272. paperwork ahead of you.  This is one of the reasons why applications cannot be
  273. written directly on top of SANA-II device drivers.
  274.  
  275. The type field allows the SANA-II device driver to fulfill CMD_READs based on
  276. the type of packet the protocol wants.  Multiple protocols can therefore run
  277. over the same wire using the same driver without stepping on each other's toes.
  278.  
  279. Packet types are now specified simply as a long word.  No current hardware
  280. uses more than a long word type and it is at all likely that a longer type
  281. field would be adapted for use in a common hardware frame within the lifetime
  282. of this standard.  Furthermore, if such a problem ever did arise, it is
  283. certainly the case that there wouldn't be more than a longword of types in use
  284. and we could provide some kind of mapping in the drivers for such a wire.
  285.  
  286. Unfortunately, the type field means different things on different wires.
  287. Protocol writers must allow their protocol to be configurable with a SANA-II
  288. device name, unit number and the type number(s) used by the protocol stack
  289. with this device.  This way if new hardware becomes available, the
  290. manufacturer-supplied listing of type assignments can be used to configure the
  291. protocol.
  292.  
  293.  
  294. Ethernet Packet Types
  295.  
  296. Ethernet has a special problem with packet types.  Two types of ethernet
  297. frames can be sent over the same wire -- ethernet and 802.3.  These frames
  298. differ in that the Type field of an ethernet frame is the Length field of an
  299. 802.3 frame.  This creates a problem in that demultiplexing incoming packets
  300. can be cumbersome and inefficient, as well as requiring protocol writers to be
  301. aware of the frame type used.
  302.  
  303. The original standard called for a generalized "Packet Magic" which all
  304. drivers and protocols had to deal with, even though few people should ever
  305. have to worry about the problem.  We could also have specified that there are
  306. 802.3 SANA-II drivers and that there are ethernet drivers and that if you want
  307. 802.3 and ethernet (even if on the same wire) from the same machine, use two
  308. ethernet boards.  This didn't make sense because we don't anticipate multiple
  309. protocols needing to use 802.3 frames nor much encouragement for hardware
  310. manufactures to provide special 802.3 drivers.  The current solution keeps the
  311. standard simple and allows highly efficient implementations, but it does make
  312. ethernet drivers a little more complex and does make using 802.3 frames harder.
  313.  
  314. SANA-II ethernet drivers return packets contained in ethernet frames normally
  315. when the requested Type does not fall within the 802.3 range (all and only
  316. 802.3 frames have numbers less than 1500 in the type field).  If a Type within
  317. the 802.3 range is requested, the driver returns the next packet contained
  318. within an 802.3 frame, regardless of the type of the packet within the 802.3
  319. frame.  This requires that there be no more than one requestor of 802.3
  320. packets and that it do it's own interpretation of the frames.
  321.  
  322.  
  323. Addressing
  324.  
  325. Network hardware addresses are stored under the SANA-II standard in an array
  326. of n bytes. No meaning is ascribed to the contents of the array by the
  327. standard.
  328.  
  329. We know of no network which does not have an address field consisting of a
  330. number of bits not divisible by eight.  In case one exists, however, any
  331. padding necessary because the number of significant bits in an address is not
  332. evenly divisible by eight belongs at the end of the bit stream.  For example,
  333. if an address is ten bits long it will be stored like this:
  334.  
  335.     98765432 10PPPPPP
  336.     BYTE 0   BYTE 1
  337.  
  338. Where the numerals are bit numbers and 'P' is a pad (ignored) bit.
  339.  
  340. Protocols which choose not to implement the bit shifting necessary to use a
  341. network with such addressing (should one exist) should at least check the
  342. number of significant bits in the address field (returned from S2_DEVICEQUERY)
  343. to make sure that it is evenly divisible by eight.
  344.  
  345. Protocols will map hardware addresses to protocol addresses in a protocol and
  346. hardware dependent manner.  Some protocols will always use the same mapping on
  347. all hardware, but other protocols will have particular address mapping schemes
  348. for some particular hardware and a reasonable default for other (unknown)
  349. hardware.
  350.  
  351. Some SANA-II devices will have "hardware addresses" which aren't really
  352. hardware addresses.  As an example, consider PPP.  PPP (Point-to-Point
  353. Protocol) is a standard for transmitting packets over a serial line.  It uses
  354. IP addresses as "hardware addresses."  The specific address to be used is
  355. negotiated during the establishment of a connection.  Thus, the address in
  356. SrcAddr returned from S2_CONFIGINTERFACE (or in a subsequent
  357. S2_GETSTATIONADDRESS) from a PPP driver will be the length of an IP address
  358. and will only be valid after the device has been configured.
  359.  
  360. Note that some hardware always uses a ROM hardware address, while other
  361. hardware which has a ROM address or is configurable with DIP switches may be
  362. overriden by software and that some hardware always dynamically allocates a
  363. new hardware address at initialization. See Configuration for details on how
  364. this is handled.
  365.  
  366.  
  367. Station Aliases
  368.  
  369. The original standard called for an interface to the ability of some hardware
  370. to simultaneously accept packets for several hardware addresses.  Such a
  371. feature is of dubious usefulness.  In order to simplify the standard, station
  372. aliases are no longer part of the SANA-II Network Device Driver Specification.
  373.  
  374. If station aliasing does turn out to be a useful feature available on some
  375. hardware for the Amiga, the standard can easily be extended to re-introduce
  376. station aliasing.  Remember that all Exec drivers must check for io_Command
  377. values not supported by the driver. Hence, SANA-II commands can be added
  378. without requiring that existing drivers be rev'd.
  379.  
  380.  
  381. Hardware Type
  382.  
  383. The HardwareType returned by S2_DEVICEQUERY is necessary for those protocols
  384. whose standards require different behavior on different hardware and for
  385. determining appropriate packet type numbers to use with the device.  The
  386. HardwareType values already issued for standard network hardware are the same
  387. as those in RFC 1060 (assigned numbers).  If you are a hardware developer with
  388. a new type of network, contact CATS to have a hardware type number assigned to
  389. you and added to the SANA-II includes.  Protocols should all have reasonable
  390. defaults for hardware with which they are not familiar.
  391.  
  392.  
  393. Errors
  394.  
  395. The SANA-II extended IORequest structure (struct IOSana2Req) includes both the
  396. ios2_Error and ios2_WireError fields.  IOSana2Reqs returned to the requester
  397. must always be checked for an error in ios2_Error.  ios2_Error will be zero if
  398. no error occurred, else it will contain a value from <exec/errors.h> or from
  399. <devices/sana2.h>.  If there was an error, there may be more specific
  400. information in ios2_WireError.  Drivers are required to fill in the WireError
  401. if there is an applicable error code.
  402.  
  403.  
  404. Error codes are #defined in the "defined errors" sections of <devices/sana2.h>:
  405.  
  406. IOSana2Req S2io_Error field (S2ERR_xxx):
  407.  
  408.     NO_RESOURCES
  409. Insufficient resources available.
  410.  
  411.     BAD_ARGUMENT
  412. Noticeably bad argument.
  413.  
  414.     BAD_STATE
  415. Command inappropriate for current state.
  416.  
  417.     BAD_ADDRESS
  418. Noticably bad address.
  419.  
  420.     MTU_EXCEEDED
  421. Write data too large.
  422.  
  423.     NOT_SUPPORTED
  424. Command is not supported by this driver. This is similar to IOERR_NOCMD as
  425. defined in <exec/errors.h> but S2ERR_NOT_SUPPORTED indicates that the
  426. requested command is a valid SANA-II command and that the driver does not
  427. support it because the hardware is incapable of supporting it (e.g.,
  428. S2_MULTICAST).  Note that IOERR_NOCMD is still valid for reasons other than a
  429. lack of hardware support (i.e., commands which are no-ops in a SANA-II driver).
  430.  
  431.     SOFTWARE
  432. Software error of some kind.
  433.  
  434.     OUTOFSERVICE
  435. When a protocol is taken offline, any pending requests are returned with this
  436. error.
  437.  
  438.     SEE ALSO the standard errors in <exec/errors.h>.
  439.  
  440.  
  441. IOSana2Req S2io_WireError field (S2WERR_xxx):
  442.  
  443.     NOT_CONFIGURED
  444. Command requires unit to be configured.
  445.  
  446.     UNIT_ONLINE
  447. Command requires that the unit be offline.
  448.  
  449.     UNIT_OFFLINE
  450. Command requires that the unit be online.
  451.  
  452.     ALREADY_TRACKED
  453. Protocol is already being tracked.
  454.  
  455.     NOT_TRACKED
  456. Protocol is not being tracked.
  457.  
  458.     BUFF_ERROR
  459. Buffer management function error return caused error.
  460.  
  461.     SRC_ADDRESS
  462. Problem with the source address field.
  463.  
  464.     DST_ADDRESS
  465. Problem with destination address field.
  466.  
  467.     BAD_BROADCAST
  468. Problem with an attempt to broadcast.
  469.  
  470.     BAD_MULTICAST
  471. Problem with an attempt to multicast.
  472.  
  473.     ALIAS_LIST_FULL
  474. Station alias list full.
  475.  
  476.     BAD_ALIAS
  477. Bad or unknown station alias.
  478.  
  479.     MULTICAST_FULL
  480. Multicast address list full.
  481.  
  482.     BAD_EVENT
  483. Event specified is unknown.
  484.  
  485.     BAD_STATDATA
  486. The S2IO_StatData pointer or the data it points to failed a sanity check.
  487.  
  488.     IS_CONFIGURED
  489. Attempt to reconfigure the unit.
  490.  
  491.     NULL_POINTER
  492. A NULL pointer was detected in one of the arguments.  S2ERR_BAD_ARGUMENT
  493. should always be the S2ERR.
  494.  
  495.  
  496. Standard Commands
  497.  
  498. See the autodocs for full details on each of the Exec device standard and
  499. SANA-II device extended commands.  Extended commands are explained in the
  500. sections below.
  501.  
  502. Many of the Exec device standard commands are no-ops in SANA-II devices, but
  503. some of these might become used in the future depending on the needs of new
  504. hardware for which SANA-II devices are implemented.  For example, CMD_RESET
  505. might someday be used for dynamically reconfiguring hardware on which this is
  506. useful.  This should present no compatibility problems.
  507.  
  508.  
  509. Broadcast and Multicast
  510.  
  511. S2_ADDMULTICASTADDRESS
  512. S2_DELMULTICASTADDRESS
  513. S2_MULTICAST
  514. S2_BROADCAST
  515.  
  516. Some hardware supports broadcast and/or multicast.  A broadcast is a packet
  517. which is sent to all other machines.  A multicast is a packet which is sent to
  518. a set of machines. Drivers for hardware which does not allow broadcast or
  519. multicast will return ios2_Error S2ERR_NOT_SUPPORTED on an attempt to use an
  520. inappropriate function.
  521.  
  522. To send a broadcast, just use S2_BROADCAST instead of CMD_WRITE.  Broadcasts
  523. are received just like any other packets, with a CMD_READ for the appropriate
  524. packet type.
  525.  
  526. To send a multicast, just use S2_MULTICAST instead of CMD_WRITE.  To receive a
  527. multicast, the multicast address to be listened on must be added with
  528. S2_ADDMULTICASTADDRESS and then a CMD_READ must be placed for the type of
  529. packet to be received.  Some SANA-II devices which support multicast may have
  530. a limited number of multicast addresses which can be listened on
  531. simultaneously so you must thus check for S2WERR_MULTICAST_FULL when adding a
  532. multicast address.
  533.  
  534. Note that when a multicast address is added, it is usually added for all users
  535. of the device, not just the protocol which called S2_ADDMULTICASTADDRESS.  In
  536. other words, if packets of a type you are requesting are multicast to an
  537. address for which S2_ADDMULTICAST has been called, you will receive these
  538. packets even if you didn't add any multicast addresses.
  539.  
  540. In general, when you receive a packet, you should not care how the packet was
  541. sent, only that it got to you.  If you really want to know, however, you can
  542. check for SANA2IOB_BCAST and/or SANA2IOB_MCAST in the ios2_Flags field.
  543.  
  544. Drivers should keep a count for the number of opens on a multicast address so
  545. that they don't actually remove it until it has been S2_DELMULTICASTADDRESS'd
  546. as many times as it has been S2_ADDMULTICASTADDRESS'd
  547.  
  548.  
  549. Stats
  550.  
  551. S2_TRACKTYPE
  552. S2_UNTRACKTYPE
  553. S2_GETTYPESTATS
  554. S2_GETSPECIALSTATS
  555. S2_GETGLOBALSTATS
  556. S2_READORPHAN
  557.  
  558. There are many statistics which may be very important to the protocol writer
  559. trying to debug, optimize and tune an implementation as well as to the end
  560. user who may need to tune parameters or investigate a problem.  Some of these
  561. statistics can only be kept by the SANA-II driver, and there are thus many
  562. required and optional statistics and commands to get at these.
  563.  
  564. S2_TRACKTYPE tells the device driver to gather statistics for a particular
  565. packet type. S2_UNTRACKTYPE tells it to stop (keeping statistics by type
  566. causes the driver to use additional resources).  S2_GETTYPESTATS returns any
  567. statistics accumulated by the driver for a type being tracked (stats are lost
  568. when a type is S2_UNTRACKTYPE'd).  Drivers are required to implement the
  569. functionality of type tracking.  The stats are returned in a struct
  570. Sana2PacketTypeStats:
  571.  
  572.     struct Sana2PacketTypeStats
  573.     {
  574.         ULONG PacketsSent;
  575.         ULONG PacketsReceived;
  576.         ULONG BytesSent;
  577.         ULONG BytesReceived;
  578.         ULONG PacketsDropped;
  579.     };
  580.  
  581.     PacketsSent
  582. Number of packets of a particular type sent.
  583.  
  584.     PacketsReceived
  585. Number of packets of a particular type that satisfied a read command.
  586.  
  587.     BytesSent
  588. Number of bytes of data sent in packets of a particular type.
  589.  
  590.     BytesReceived
  591. Number of bytes of data of a particular packet type that satisfied a read
  592. command.
  593.  
  594.     PacketsDropped
  595. Number of packets of a particular type that were received while there were no
  596. pending reads of that packet type.
  597.  
  598.  
  599. S2_GETGLOBALSTATS returns global statistics kept by the driver.  Drivers are
  600. required to keep all applicable statistics, and most drivers will therefore
  601. keep all of them.  The stats are returned in a struct Sana2DeviceStats:
  602.  
  603.     struct Sana2DeviceStats
  604.     {
  605.         ULONG PacketsReceived;
  606.         ULONG PacketsSent;
  607.         ULONG BadData;
  608.         ULONG Overruns;
  609.         ULONG UnknownTypesReceived;
  610.         ULONG Reconfigurations;
  611.         struct timeval LastStart;
  612.     };
  613.  
  614.     PacketsReceived
  615. Number of packets that this unit has received.
  616.  
  617.     PacketsSent
  618. Number of packets that this unit has sent.
  619.  
  620.     BadData
  621. Number of bad packets received (i.e., hardware CRC failed).
  622.  
  623.     Overruns
  624. Number of packets dropped due to insufficient resources available in the
  625. network interface.
  626.  
  627.     UnknownTypeReceived
  628. Number of packets received that had no pending read command with the
  629. appropriate packet type.
  630.  
  631.  
  632.     Reconfigurations
  633. Number of network reconfigurations since this unit was last configured.
  634.  
  635.     LastStart
  636. The time when this unit last went online.
  637.  
  638.  
  639. S2_GETSPECIALSTATS returns any special statistics kept by a particular driver.
  640. It is hoped that each wire type will have a set of documented required
  641. statistics for that wire type and a standard set of optional statistics for
  642. that wire type (optional because they might not be available from all
  643. hardware).  The data returned by S2_GETSPECIALSTATS will require wire-specific
  644. interpretation, see <devices/sana2specialstats.h> for currently defined
  645. special statistics.  The statistics are returned in the following structures:
  646.  
  647.     struct Sana2SpecialStatRecord
  648.     {
  649.         ULONG Type;
  650.         ULONG Count;
  651.         char *String;
  652.     };
  653.  
  654.     Type
  655. Statistic identifier.
  656.  
  657.     Count
  658. Statistic itself.
  659.  
  660. String
  661. Identifying string for the statistic. Should be plain ASCII with no formatting
  662. characters.
  663.  
  664.  
  665.     struct Sana2SpecialStatHeader
  666.     {
  667.         ULONG RecordCountMax;
  668.         ULONG RecordCountSupplied;
  669.         struct Sana2SpecialStatRecord[RecordCountMax];
  670.     };
  671.  
  672.     RecordCountMax
  673. Space for this many number of records is available to place statistics
  674. information in.
  675.  
  676.     RecordCountSupplied
  677. Number of statistic records supplied.
  678.  
  679.  
  680. S2_READORPHAN is not, strictly speaking, a statistical function.  It is a
  681. request to read any packet of a type for which there is no outstanding
  682. CMD_READ.  S2_READORPHAN might be used in the same manner as many statistics,
  683. though, such as to determine what packet types are causing overruns, etc.
  684.  
  685.  
  686. Configuration
  687.  
  688. S2_DEVICEQUERY
  689. S2_GETSTATIONADDRESS
  690. S2_CONFIGINTERFACE
  691.  
  692. Network hardware needs to be configured before it is used.  Some parameters
  693. about the hardware must be known by protocol software (hardware address and
  694. MTU, for example) when it is used.  These commands address those needs.
  695.  
  696. When a network protocol is started, it should try to S2_CONFIGINTERFACE even
  697. though an interface can only be configured once and someone else may have done
  698. it.  In order to properly S2_CONFIGINTERFACE, you must first
  699. S2_GETSTATIONADDRESS to determine the factory address (if any).  You must also
  700. provide for user-override of the factory address (that address may be optional
  701. and the user may need to override it).  When S2_CONFIGINTERFACE returns, you
  702. must check the ios2_SrcAddr for the actual address the hardware has been
  703. configured with.  This is because some hardware (or serial line standards such
  704. as PPP) always dynamically allocates an address at initialization.
  705.  
  706. Protocol writers will want to use S2_DEVICEQUERY to determine the MTU and
  707. other characteristics of the network.  The structure returned from
  708. S2_DEVICEQUERY is defined as:
  709.  
  710.     struct Sana2DeviceQuery
  711.     {
  712.         ULONG SizeAvailable;
  713.         ULONG SizeSupplied;
  714.         ULONG DevQueryFormat;
  715.         ULONG DeviceLevel;
  716.         UWORD AddrFieldSize;
  717.         ULONG MTU;
  718.         ULONG BPS;
  719.         ULONG HardwareType;
  720.     };
  721.  
  722.     SizeAvailable
  723. Size, in bytes, of the space available in which to place device information.
  724. This includes both size fields.
  725.  
  726.     SizeSupplied
  727. Size, in bytes, of the data supplied.
  728.  
  729.     DevQueryFormat
  730. The format defined here is format 0.
  731.  
  732.     DeviceLevel
  733. This spec defines level 0.
  734.  
  735.     AddrFieldSize
  736. The number of bits in an interface address.
  737.  
  738.     MTU
  739. Maximum Transmission Unit, the size, in bytes, of the maximum packet size, not
  740. including header and trailer information.
  741.  
  742. BPS
  743. Best guess at the raw line rate for this network in bits per second.
  744.  
  745.     HardwareType
  746. Specifies the type of network hardware the driver controls.
  747.  
  748.  
  749. Online
  750.  
  751. S2_ONLINE
  752. S2_OFFLINE
  753. S2_ONEVENT
  754.  
  755. In order to allow hardware tests to be run on an otherwise live system, the
  756. S2_OFFLINE command allows the SANA-II device driver to be "turned off" until
  757. the tests are complete and an ONLINE is sent to the driver.  S2_ONLINE causes
  758. the interface will be re- configured and re-initialized, and any packets
  759. destined for the hardware while the device was offline will have been lost.
  760. All pending and new requests to the driver should be returned with
  761. S2ERR_OUTOFSERVICE when a device is offline.
  762.  
  763. All protocol software must understand that any IO request may be returned with
  764. S2ERR_OUTOFSERVICE because the driver has been taken offline.  In such an
  765. event, the protocol will usually want to wait until the unit comes back
  766. S2_ONLINE.  It may do this by calling S2_ONEVENT to wait for S2EVENT_ONLINE.
  767. S2_ONEVENT allows various events for the driver to be waited on.
  768.  
  769. Events usually happen in multiples.  A driver must track events, but may not
  770. distinguish between some types of events.  If an event is not tracked, an
  771. S2_ONEVENT for the event is returned with S2_ERR_NOT SUPPORTED and
  772. S2WERR_BAD_EVENT.  Errors which seem caused by a malformed or unusual request
  773. should not generally trigger an event.
  774.  
  775. Event types (S2EVENT_xxx):
  776.  
  777.     ERROR
  778. Return when any error occurs.
  779.  
  780.     TX
  781. Return on any transmit error.  (Always an Error.)
  782.  
  783.     RX
  784. Return on any receive error.  (Always an Error.)
  785.  
  786.     ONLINE
  787. Return when unit goes online or return immediately if unit is already online.
  788. (Not an Error.)
  789.  
  790.     OFFLINE
  791. Return when unit goes offline or return immediately if unit is already
  792. offline. (Not an Error.)
  793.  
  794.     BUFF
  795. Return on any buffer management function error.  (Always an Error.)
  796.  
  797.     HARDWARE
  798. Return when any hardware error occurs.  (Always an Error, may be a TX or RX,
  799. too.)
  800.  
  801.     SOFTWARE
  802. Return when any software error occurs.  (Always an Error, may be a TX or RX,
  803. too.)
  804.